QUICKDRAW™ 3D Renderer Virtual Accelerator(RAVE) 1.5 GM Release
APPLE COMPUTER 12/5/96
Welcome to the RAVE 1.5 GM release. This developer release of RAVE includes both the SDK and DDK. To get full access to the DDK you will need to sign an NDA with Apple Computer. Once this has been done we will send you a password for the full Sneak3View test application source.
Note that these are GM builds of RAVE for MacOS and Win32. However these builds have not been approved for distribution outside of the Developer Kit.
WHAT'S NEW IN 1.5
The RAVE 1.1 release will include the implementation of additional RAVE features, new APIs, and a more functionally complete White Magic(Apple QD3D HW Plug-In) RAVE engine.
Added Implementations
1) Cache context flag when using QADrawContextNew
2) dirtyRect field in QARenderStart
3) White Magic supports all texture and bitmap formats
New APIs
1) Notification methods for render completion and underlay/overlay support
2) Texture memory gestalts
3) Texture map and bitmap compression flags
4) kQADisplayModeUnsupported error flag
The following sections give a brief descriptions of the new APIs, please see the RAVE.h header file for more information.
Notification Methods
The Notification API is used to get notified via callback when asynchronis rendering has completed, when a display mode change has occured, when a drawing engine requires you to reload all of your texture maps, or when you may draw into the backbuffer before and after rendering has completed.
Texture Memory Gestalts
Two new Gestalt Selectors have been added, kQAGestalt_TextureMemory and kQAGestalt_FastTextureMemory. These return the total amount of texture memory available and the amount of fast texture memory available. Use these as indicators for how you want to maintain the size and number of textures maps your application uses.
Texture/Bitmap Compression Flags
Two news texture and bitmap flags have been added, xxx_NoCompression, and xxx_HighCompression. The default mode is that the engine will provide some compression if it has little or no speed hit and has no appreciable difference in quality.
kQADisplayModeUnsupported Error
This error is returned when an engine is capable of rendering to a device, but the display mode has been configured so that drawing can not occur. An example would be when the display has been set to 8-bit but the engine can only render to 16 or 32.
The following is the standard readme that has been included with previous releases/
WHAT IS "QUICKDRAW 3D RAVE"?
QuickDraw 3D RAVE is a low-level abstraction layer for 3D hardware accelerators. Because RAVE is an abstraction layer, it provides a common layer which can be used to access a variety of different hardware accelerators. RAVE also provides a default software rasterizer which is always available, even on systems that don't have a hardware accelerator installed.
The QuickDraw 3D Interactive Renderer uses RAVE to do all interactive rendering. As a result, QuickDraw 3D automatically works with any hardware accelerator which has a RAVE plug-in.
ABOUT THIS RELEASE
This is the GM release of RAVE 1.5. There are currently no known bugs in the QD3D RAVE Manager or the Software Engine. However, if you find problems please report bugs to
Brent Pease
email: brent@apple.com
and
Tim Carroll
email: timc@apple.com
This release matches the hardware acceleration interface of the QuickDraw 3D 1.0 release, so any RAVE engine developed with this DR will work with QD3D 1.0 (or later) based applications. Additionally, there are new APIs in this release that will be used by QD3D 1.5 to achieve much improved immediate mode rendering performance, see the What's New section for more information. Additionally any RAVE engine developed for version 1.5 will work with older versions of QD3D.
The contents of this DDK/SDK were all developed using the Metrowerks™ development environment, from the CW10 CD. We recommend an on-line reference for Macintosh programming (e.g. the ThinkC™ Reference or QuickView™) as well, particularly if you're not an experienced Macintosh programmer.
RAVE DISTRIBUTION
RAVE is being distributed in the form of a single release which includes a DDK (Device Driver Kit) and a SDK(Software Developers Kit). The DDK is primarily for hardware vendors who are developing 3D accelerators to run with QuickDraw 3D and any other application that uses RAVE. The SDK is primarily for game developers who need direct access to low level 3D rasterization functions such as texture mapping and z-buffered drawing.
WHAT'S NEW IN 1.06
The 1.06 release contains two new APIs, the TriMesh and support for color lookup tables. These APIs are documented in the ERS(Engineering Requirements Document) that has been distributed with this release. Final documentation for RAVE will be available soon.
The new manager will decompose TriMeshes into triangles so that existing engines will still be 100% compatible with new QD3D releases. However, the managers does not provide any support for color lookup tables. This means that the engine must support it or the API calls for color lookup tables will return the error kQANotSupported.
The name of the plug-in has changed from QuickDraw 3D Acceleration Layer to QuickDraw 3D RAVE. For the curious RAVE stands for Renderer Accelerator Virtual Engine.
TESTLINKED/TESTSHARED
TestLinked and TestShared are two versions of the RAVE_Test application. The only difference between these versions is that TestLinked directly links in the empty drawing engine (described below), while TestShared loads the engine through the RAVE plug-in mechanism. You can use whichever version of RAVE_Test you like; usually it's easier to begin using the TestLinked version, and move to the TestShared version later. Note that you use the "SharedEmpty.µ" project to build your drawing engine as a shared library before you can use TestShared; see "USING SHARED LIBRARIES" below for more discussion. Note that TestLinked will produce a warning message about ignoring a duplicate engine, please ignore it. Tthe reason for this is that the engine is linked in with the application and is present as a shared library.
RAVE_Test opens two windows, using a different drawing engine for each window, and runs a series of simple RAVE rendering tests to both windows. RAVE_Test is primarily for vendors developing their own drawing engine, as it provides a convenient way to compare your results with those from the Apple Software drawing engine. However, this application also provides sample application code for how to use RAVE for drawing.
RAVE_Test runs tests that draw points, lines, Gouraud triangles and texture triangles. Each test is run four ways: Single buffered, double buffered, single buffered with 2D clipping, and double buffered with 2D clipping.
EMPTY ENGINE
RAVE_Test includes "Empty Engine", a sample RAVE drawing engine with empty stubs for the drawing functions. This provides a convenient place to begin implementing a drawing engine. The TestLinked.µ project file links "Empty Engine" directly with the RAVE_Test application, so when you run it the second window is assigned to "Empty Engine". Nothing appears there, of course, as "Empty Engine" doesn't do anything. But that proves that it has actually been registered with the RAVE manager! See "USING SHARED LIBRARIES", below, for how to build "Empty Engine" as a shared library instead of linking it directly.
SNEAK3VIEW
Sneak3View is a much more powerful test and verification application. It's build with Metrowerks PowerPlant. Please look in the Sneak3View folder for more information.
QUICKDRAW™ 3D RAVE
"QuickDraw™ 3D RAVE" is a shared library that contains the RAVE manager and Apple's software rasterizer. You need to link with it whenever you are making RAVE calls. Two versions are included, in two folders called "QD3D RAVE (debug on)" and "QD3D RAVE (debug off)". The debug on version does extensive parameter and semantic checking of all RAVE calls; this is particularly useful when you are developing application code that drives RAVE. The debug off version is the optimized release shipped with QuickDraw 3D 1.0, and performs no (or minimal) validation checking.
If you are developing a drawing engine, and you're confident that the application code is correct, you may find it more convenient to develop with the "QuickDraw™ 3D RAVE" library that has debug turned off. This is because the debug on version actually inserts it's own functions and data types between the application calls (e.g. QADrawPoint()) and the drawing engine. If you use the debug off library, calls like this pass directly to your engine's code, which may be more convenient for debugging.
APPLE SOFTWARE RASTERIZER
This release includes "QuickDraw™ 3D RAVE" version 1.5, which includes a software plug-in which implements a complete (although basic) RAVE feature set. Some notes on the software rasterizer features:
— Rendering to any GDevice, and to 16 or 32 bit memory devices is supported. Rendering is optimized for 16 and 32 bit deep GDevices; all others are supported by rendering 16 bits offscreen and then blitting.
— Texture mapping is point-sampled from the closest mipmap level.
HEADERS
This folder holds the RAVE.h and RAVE_system.h header files, as described by the RAVE ERS. RAVE.h should be included by application code that uses RAVE. RAVE_system.h is only required by drawing engine code. Note that Drive3D.h and Drive3D_system.h have been included for backwards compatibility and they simply #include their corresponding new filename.
USING SHARED LIBRARIES
Your preferred "QuickDraw™ 3D RAVE" library (i.e. with or without debugging) needs to be either in your application's folder (usually the most convenient for development) or in the System Extensions folder. The same is true of your drawing engine shared library (if present). In this DR we've placed a copy of the debug-on "QuickDraw™ 3D RAVE" library in the application folder, so right now the RAVE_Test application is being run with debug on.
Once your drawing engine is stable, you may prefer to build it as a RAVE shared library. The "SharedEmpty.µ" project demonstrates how to do this. In general it's pretty easy: Just build a shared library with creator 'tnsl', and call QARegisterEngine() from your init function. WARNING: Once you have built your engine this way, you should switch to using the TestShared application, as it will confuse the RAVE manager to have your drawing engine both linked in and as a shared library!
As an experiment, try running the TestShared application _without_ the EmptyEngine plug-in in the application folder. The second window will be named "<No Drawing Engine>", indicating that the application wasn't able to find a second drawing engine to load. If you move EmptyEngine back into the application folder, the window will be titled "Empty Drawing Engine", indicating that the plug-in is being loaded.
Another experiment is to run TestLinked _with_ EmptyEngine in the folder. If you use the debug library, this will cause a warning message indicating that a duplicate drawing engine is being ignored. This is because the engine was registered twice, once from the linked version, and once via the plug-in mechanism. Therefore, if you're using TestLinked, you should not have a shared library version of the engine present as well.
